﻿//---------------------------------------------------------------------------------
// Copyright 2011 Microsoft Corporation
// Licensed under the Microsoft Public License (MS-PL) (the "License"); 
// You may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.opensource.org/licenses/ms-pl.html
// THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR 
// CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, 
// INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OR 
// CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 
// MERCHANTABLITY OR NON-INFRINGEMENT. 
// See the Microsoft Public License (MS-PL) for the specific language governing 
// permissions and limitations under the License.
//---------------------------------------------------------------------------------

using System.Collections.Generic;
using System.ServiceModel;

namespace Microsoft.Telco.Web.Contracts
{
	/// <summary>
	/// Provides signatures for interacting with the Telco Gateway service.
	/// </summary>
	[ServiceContract(Namespace = Namespaces.V1)]
	public interface IGatewayService
	{

		/// <summary>
		/// Sends an SMS message.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="originAddress">The phone number the message comes from</param>
        /// <param name="destinationAdresses">Phone numbers to send SMS to.</param>
		/// <param name="message">The SMS message.</param>
		/// <returns>The message Id that can be used to query message delivery status</returns>
		[OperationContract]
		[FaultContract(typeof(TelcoFault))]
		[FaultContract(typeof(AuthenticationFault))]
		string SendSMS(string userId, string originAddress, string[] destinationAdresses, string message);

		/// <summary>
		/// Gets the SMS status.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
		/// <param name="messageId">The message id.</param>
		/// <returns>The message delivery status</returns>
		[OperationContract]
		[FaultContract(typeof(TelcoFault))]
		[FaultContract(typeof(AuthenticationFault))]
		List<MessageStatus> GetSMSStatus(string userId, string messageId);

        /// <summary>
        /// Gets SMS messages for the application.
        /// </summary>
        /// <remarks>
        /// The invocation of GetSMSMessages retrieves all the SMS messages received that fullfil the
        /// criteria identified by userId. 
        /// </remarks>
        /// <param name="userId">The id of the user sending the message</param>
        /// <returns></returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        [FaultContract(typeof(AuthenticationFault))]
        List<ShortMessage> GetSMSMessages(string userId);

        /// <summary>
        /// Sends an MMS message.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="originAddress">The phone number the message comes from</param>
        /// <param name="destinationAddresses">Phone numbers to send MMS to.</param>
        /// <param name="messageParts">A collection of attachments to be sent</param>
        /// <returns>The message Id that can be used to query message delivery status</returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        [FaultContract(typeof(AuthenticationFault))]
        string SendMMS(string userId, string originationAddress, List<string> destinationAddresses, List<MultimediaMessage> messageParts);

        /// <summary>
        /// Gets the MMS status.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="messageId">The message id.</param>
        /// <returns>The message delivery status</returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        [FaultContract(typeof(AuthenticationFault))]
        List<MessageStatus> GetMMSStatus(string userId, string messageId);

        /// <summary>
        /// Gets MMS messages for the application.
        /// </summary>
        /// <remarks>
        /// The invocation of GetMMSMessages retrieves all the MMS messages received that fullfil the
        /// criteria identified by UserId.
        /// </remarks>
        /// <param name="userId">The id of the user sending the message</param>
        /// <returns>The collection of messages for the specified user</returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        [FaultContract(typeof(AuthenticationFault))]
        List<MultimediaMessage> GetMMSMessages(string userId);

		/// <summary>
		/// Gets the advertisement.
		/// </summary>
		/// <param name="request">The request.</param>
		/// <returns>The requested advertisement</returns>
		[OperationContract]
		[FaultContract(typeof(TelcoFault))]
		[FaultContract(typeof(AuthenticationFault))]
		Advertisement GetAdvertisement(AdvertisementRequest request);

		/// <summary>
		/// Gets the user's contacts.
		/// </summary>
		/// <returns></returns>
		[OperationContract]
		[FaultContract(typeof(TelcoFault))]
		[FaultContract(typeof(AuthenticationFault))]
		List<LiveContact> GetContacts();

        /// <summary>
        /// Converts the text to speech.
        /// </summary>
        /// <param name="text">The text.</param>
        /// <returns>Audio of the provided speech</returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        Attachment ConvertTextToSpeech(string text);

        /// <summary>
        /// Transcribes the voice.
        /// </summary>
        /// <param name="attachment">The attachment.</param>
        /// <returns>The transcribed speech</returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        string TranscribeVoice(Attachment attachment);

        /// <summary>
        /// Creates a call between the origin and destination
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="origin">The origin of the call request.</param>
        /// <param name="destination">The remote endpoint to be connected on this call.</param>
        /// <param name="connectionText">Text provided on connection</param>
        /// <returns>The status of the call</returns>
        [OperationContract]
        [FaultContract(typeof(TelcoFault))]
        string CreateClickToCall(string userId, string origin, string destination, string connectionText);

	}
}
